JBoss.orgCommunity Documentation
The Mobicents SIP Presence Service is built on top of Mobicents JAIN SLEE, which means JAIN SLEE applications can be deployed and run in same JVM as the servers. Better yet, there are XDM and SIP Presence client enablers which can be integrated in such JAIN SLEE applications, allowing an easy interaction with the platform servers.
The Mobicents SIP Presence exposes a JAIN SLEE enabler for applications which want to interact as clients of the XDM Server. The enabler is an extension of the XDM Client Enabler which exists in Mobicents JAIN SLEE, the only difference is that upon requests targeting the local and integrated XDM Server, the enabler does not uses XCAP or SIP network protocols, thus providing better performance and less overhead to network communications.
Please refer to the bundled JAIN SLEE documentation for complete details about how to integrate the enabler, the only difference to note in this document, is the configuration of the client JAIN SLEE application SBB's XML Descriptor. The extended XDM Client Enabler SBB has the following ID:
<sbb-name>InternalXDMClientControlSbb</sbb-name>
<sbb-vendor>org.mobicents</sbb-vendor>
<sbb-version>1.0</sbb-version>
In concrete this means that when integrating the enabler, the Parent's (the client application) Sbb XML Descriptor will refer the ID above instead of:
<sbb-name>XDMClientChildSbb</sbb-name>
<sbb-vendor>org.mobicents</sbb-vendor>
<sbb-version>1.0</sbb-version>
The Mobicents SIP Event Publication exposes a JAIN SLEE enabler for applications which want to interact as clients of a SIP Event Publication Server. The enabler does not uses SIP network protocols, thus providing better performance and less overhead to network communications.
The Enabler consists in an SBB which can be used in child relations, with a simple synchronous interface.
This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.
In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.
The Service's Sbb will be referred as the Parent Sbb in the following sections.
The Mobicents SIP Event Publication Client Enabler Sbb does not provides asynchronous callbacks to the Parent's Sbb at the moment, that is, all operations invoked in the child sbb will return a response. Thus the Parent does not needs to implement a specific interface.
The Enabler's Sbb is a Child Sbb, and JAIN SLEE 1.1 Child Relations requires an abstract method in the Sbb Abstract Class, to retrieve the javax.slee.ChildRelation
object, which is used to create or access specific Child Sbbs. This method should be:
public abstract ChildRelation getSIPEventPublicationClientChildRelation();
The Parent's Sbb must define a reference to the Enabler's Child Sbb, declare which is the method name to get the related ChildRelation object, and also ensure the SbbLocalObject interface is defined correctly.
A reference to the Enabler's Child Sbb is defined right after the Parent's Sbb Vendor ID element, using the following XML element:
<sbb-ref>
<sbb-name>PublicationControlSbb</sbb-name>
<sbb-vendor>org.mobicents</sbb-vendor>
<sbb-version>1.0</sbb-version>
<sbb-alias>sipEventPublicationClientChildSbb</sbb-alias>
</sbb-ref>
The method name to get the Enabler's ChildRelation object must be defined after the CMP Fields (if any), this XML element links the sbb-alias previously defined with the abstract method declared in the Parent's Sbb Abstract Class:
<get-child-relation-method>
<sbb-alias-ref>sipEventPublicationClientChildSbb</sbb-alias-ref>
<get-child-relation-method-name>getSIPEventPublicationClientChildRelation</get-child-relation-method-name>
<default-priority>0</default-priority>
</get-child-relation-method>
In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.
The Mobicents SIP Event Publication Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sipevent.server.publication.PublicationClientControlSbbLocalObject
, which extends the javax.slee.SbbLocalObject
and org.mobicents.slee.sipevent.server.publication.PublicationClientControl
interfaces, the latter declares the methods which can be used to interact with the PS and/or RLS:
package org.mobicents.slee.sipevent.server.publication;
public interface PublicationClientControl {
public Result newPublication(String entity, String eventPackage,
String document, String contentType, String contentSubType,
int expires);
public Result refreshPublication(String entity, String eventPackage,
String eTag, int expires);
public Result modifyPublication(String entity, String eventPackage,
String eTag, String document, String contentType,
String contentSubType, int expires);
public int removePublication(String entity, String eventPackage, String eTag);
}
newPublication(String, String, String, String, String, int)
method:Requests a new publication, for the specified Entity and SIP Event Package.
refreshPublication(String, String, String, int)
method:Requests a publication refresh, for the specified Entity, SIP Event Package and ETag.
modifyPublication(String, String, String, String, String, String, int)
method:Requests a publication modification, for the specified Entity, SIP Event Package and ETag.
removePublicationOk(String, String, String)
method:Requests a publication removal, for the specified Entity, SIP Event Package and ETag.
The Child Relation in the Parent Sbb Abstract Class is used to create and retrieve the Child Sbb, it is important to not forget to pass the Parent's SbbLocalObject to the Child after creation:
public PublicationClientControl getPresenceClientChildSbb() {
final ChildRelation childRelation = getSIPEventPublicationClientChildRelation();
if (childRelation.isEmpty()) {
try {
// creates new instance
return (PublicationClientControl) childRelation.create();
} catch (Exception e) {
tracer.severe("Failed to create child sbb", e);
return null;
}
}
else {
// reuse the existent one
return (PublicationClientControl) childRelation.iterator().next();
}
}
The Mobicents SIP Event Publication exposes a JAIN SLEE enabler for applications which want to interact as clients of a SIP Event Subscription Server, such as a PS or RLS. The enabler does not uses SIP network protocols, thus providing better performance and less overhead to network communications.
The Enabler consists in an SBB which can be used in child relations, with a simple asynchronous interface.
This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.
In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.
The Service's Sbb will be referred as the Parent Sbb in the following sections.
The Mobicents SIP Event Subscription Client Enabler Sbb provides asynchronous callbacks to the Parent's Sbb, and that can only be achieved if the Parent's SbbLocalObject extends a specific Java interface, deployed also by the Enabler, and provides it's SbbLocalObject to the Enabler's Sbb, through a specific method exposed by the latter interface. The Enabler stores the Parent's SbbLocalObject and uses it when a callback to the Parent's Sbb is needed.
The SbbLocalObject which must be used or extended by the Parent's Sbb is named org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlParentSbbLocalObject
, which extends the javax.slee.SbbLocalObject
and org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlParent
interfaces, the latter declares the callbacks which must be implemented in the Parent's Sbb Abstract Class:
package org.mobicents.slee.sipevent.server.subscription;
import org.mobicents.slee.sipevent.server.subscription.data.Subscription;
public interface SubscriptionClientControlParent {
public void subscribeOk(String subscriber, String notifier,
String eventPackage, String subscriptionId, int expires,
int responseCode);
public void resubscribeOk(String subscriber, String notifier,
String eventPackage, String subscriptionId, int expires);
public void unsubscribeOk(String subscriber, String notifier,
String eventPackage, String subscriptionId);
public void subscribeError(String subscriber, String notifier,
String eventPackage, String subscriptionId, int error);
public void resubscribeError(String subscriber, String notifier,
String eventPackage, String subscriptionId, int error);
public void unsubscribeError(String subscriber, String notifier,
String eventPackage, String subscriptionId, int error);
public void notifyEvent(String subscriber, String notifier,
String eventPackage, String subscriptionId,
Subscription.Event terminationReason, Subscription.Status status,
String content, String contentType, String contentSubtype);
}
subscribeOk(String, String, String, String, int, int)
method:Callback from the Enabler indicating that the new subscription request succeed.
resubscribeOk(String, String, String, String, int)
method:Callback from the Enabler indicating that the refresh subscription request succeed.
unsubscribeOk(String, String, String, String)
method:Callback from the Enabler indicating that the remove subscription request succeed.
subscribeError(String, String, String, String, int)
method:Callback from the Enabler indicating that the new subscription request failed.
resubscribeError(String, String, String, String, int)
method:Callback from the Enabler indicating that the refresh subscription request failed.
unsubscribeError(String, String, String, String, int)
method:Callback from the Enabler indicating that the remove subscription request failed.
notifyEvent(String, String, String, String, Subscription.Event, Subscription.Status, String, String, String)
method:Callback from the Enabler notifying an event related with notifier state change.
The Parent Sbb Abstract Class must implement the callbacks on it's SbbLocalObject, that is, must implement the org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlParent
interface discussed in last section.
The Enabler's Sbb is a Child Sbb, and JAIN SLEE 1.1 Child Relations requires an abstract method in the Sbb Abstract Class, to retrieve the javax.slee.ChildRelation
object, which is used to create or access specific Child Sbbs. This method should be:
public abstract ChildRelation getSIPEventSubscriptionClientChildRelation();
The Parent's Sbb must define a reference to the Enabler's Child Sbb, declare which is the method name to get the related ChildRelation object, and also ensure the SbbLocalObject interface is defined correctly.
A reference to the Enabler's Child Sbb is defined right after the Parent's Sbb Vendor ID element, using the following XML element:
<sbb-ref>
<sbb-name>SubscriptionControlSbb</sbb-name>
<sbb-vendor>org.mobicents</sbb-vendor>
<sbb-version>1.0</sbb-version>
<sbb-alias>sipEventSubscriptionClientChildSbb</sbb-alias>
</sbb-ref>
The method name to get the Enabler's ChildRelation object must be defined after the CMP Fields (if any), this XML element links the sbb-alias previously defined with the abstract method declared in the Parent's Sbb Abstract Class:
<get-child-relation-method>
<sbb-alias-ref>sipEventSubscriptionClientChildSbb</sbb-alias-ref>
<get-child-relation-method-name>getSIPEventSubscriptionClientChildRelation</get-child-relation-method-name>
<default-priority>0</default-priority>
</get-child-relation-method>
Finally, after the sbb-abstract-class
element the Parent's SbbLocalObject interface name is defined:
<sbb-local-interface>
<sbb-local-interface-name>...</sbb-local-interface-name>
</sbb-local-interface>
In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.
The Mobicents SIP Event Subscription Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlSbbLocalObject
, which extends the javax.slee.SbbLocalObject
and org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlSbbLocalObject
interfaces, the latter declares the methods which can be used to interact with the SIP Event Subscription Server:
package org.mobicents.slee.sipevent.server.subscription;
public interface SubscriptionClientControl {
public void setParentSbb(
SubscriptionClientControlParentSbbLocalObject sbbLocalObject);
public void subscribe(String subscriber, String subscriberdisplayName,
String notifier, String eventPackage, String subscriptionId,
int expires, String content, String contentType,
String contentSubtype);
public void resubscribe(String subscriber, String notifier,
String eventPackage, String subscriptionId, int expires);
public void unsubscribe(String subscriber, String notifier,
String eventPackage, String subscriptionId);
}
setParentSbb(SubscriptionClientControlParentSbbLocalObject)
method:Passes the Parent's SbbLocalObject, which will be used by the Child Sbb to provide async results. If not invoked after the child creation the Enabler won't be able to callback the Parent Sbb.
subscribe(String, String, String, String, String, int, String, String, String)
method:Requests a new subscription.
resubscribe(String, String, String, String, int)
method:Requests a subscription refresh.
unsubscribe(String, String, String, String)
method:Requests a subscription removal.
The Child Relation in the Parent Sbb Abstract Class is used to create and retrieve the Child Sbb, it is important to not forget to pass the Parent's SbbLocalObject to the Child after creation:
public SubscriptionClientControl getSIPEventSubscriptionClientChildSbb() {
final ChildRelation childRelation = getSIPEventSubscriptionClientChildRelation();
if (childRelation.isEmpty()) {
try {
// creates new instance
SubscriptionClientControl sbb = (SubscriptionClientControl) childRelation.create();
// passes the parent sbb local object to the child
sbb.setParentSbb((SubscriptionClientControlParentSbbLocalObject) sbbContext.getSbbLocalObject());
return sbb;
} catch (Exception e) {
tracer.severe("Failed to create child sbb", e);
return null;
}
}
else {
// reuse the existent one
return (SubscriptionClientControl) childRelation.iterator().next();
}
}
The Mobicents SIP Presence exposes a JAIN SLEE enabler for applications which want to interact as clients of the Presence (PS) or Resource List Server (RLS). The enabler does not uses SIP network protocols, thus providing better performance and less overhead to network communications.
The Enabler consists in an SBB which can be used in child relations, with a simple asynchronous interface.
The Presence Client Enabler reuses the SIP Event Subscription and Publication Client Enablers, and for the best performance it is best to use these instead. This is due to less internal state needed.
This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.
In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.
The Service's Sbb will be referred as the Parent Sbb in the following sections.
The Mobicents Presence Client Enabler Sbb provides asynchronous callbacks to the Parent's Sbb, and that can only be achieved if the Parent's SbbLocalObject extends a specific Java interface, deployed also by the Enabler, and provides it's SbbLocalObject to the Enabler's Sbb, through a specific method exposed by the latter interface. The Enabler stores the Parent's SbbLocalObject and uses it when a callback to the Parent's Sbb is needed.
The SbbLocalObject which must be used or extended by the Parent's Sbb is named org.mobicents.slee.sippresence.client.PresenceClientControlParentSbbLocalObject
, which extends the javax.slee.SbbLocalObject
and org.mobicents.slee.sippresence.client.PresenceClientControlParent
interfaces, the latter declares the callbacks which must be implemented in the Parent's Sbb Abstract Class:
package org.mobicents.slee.sippresence.client;
import org.mobicents.slee.sipevent.server.subscription.data.Subscription;
public interface PresenceClientControlParent {
public void newPublicationOk(Object requestId, String eTag, int expires);
public void refreshPublicationOk(Object requestId, String eTag, int expires);
public void modifyPublicationOk(Object requestId, String eTag, int expires);
public void removePublicationOk(Object requestId);
public void newPublicationError(Object requestId, int error);
public void refreshPublicationError(Object requestId, int error);
public void modifyPublicationError(Object requestId, int error);
public void removePublicationError(Object requestId, int error);
public void newSubscriptionOk(String subscriber, String notifier,
String eventPackage, String subscriptionId, int expires,
int responseCode);
public void refreshSubscriptionOk(String subscriber, String notifier,
String eventPackage, String subscriptionId, int expires);
public void removeSubscriptionOk(String subscriber, String notifier,
String eventPackage, String subscriptionId);
public void newSubscriptionError(String subscriber, String notifier,
String eventPackage, String subscriptionId, int error);
public void refreshSubscriptionError(String subscriber, String notifier,
String eventPackage, String subscriptionId, int error);
public void removeSubscriptionError(String subscriber, String notifier,
String eventPackage, String subscriptionId, int error);
public void notifyEvent(String subscriber, String notifier,
String eventPackage, String subscriptionId,
Subscription.Event terminationReason, Subscription.Status status,
String content, String contentType, String contentSubtype);
}
newPublicationOk(Object, String, int)
method:Callback from the Enabler indicating that the new publication request succeed.
refreshPublicationOk(Object, String, int)
method:Callback from the Enabler indicating that the refresh publication request succeed.
modifyPublicationOk(Object, String, int)
method:Callback from the Enabler indicating that the modify publication request succeed.
removePublicationOk(Object)
method:Callback from the Enabler indicating that the remove publication request succeed.
newPublicationError(Object, int)
method:Callback from the Enabler indicating that the new publication request failed.
refreshPublicationError(Object, int)
method:Callback from the Enabler indicating that the refresh publication request failed.
modifyPublicationError(Object, int)
method:Callback from the Enabler indicating that the modify publication request failed.
removePublicationError(Object, int)
method:Callback from the Enabler indicating that the remove publication request failed.
newSubscriptionOk(String, String, String, String, int, int)
method:Callback from the Enabler indicating that the new subscription request succeed.
refreshSubscriptionOk(String, String, String, String, int)
method:Callback from the Enabler indicating that the refresh subscription request succeed.
removeSubscriptionOk(String, String, String, String)
method:Callback from the Enabler indicating that the remove subscription request succeed.
newSubscriptionError(String, String, String, String, int)
method:Callback from the Enabler indicating that the new subscription request failed.
refreshSubscriptionError(String, String, String, String, int)
method:Callback from the Enabler indicating that the refresh subscription request failed.
removeSubscriptionError(String, String, String, String, int)
method:Callback from the Enabler indicating that the remove subscription request failed.
notifyEvent(String, String, String, String, Subscription.Event, Subscription.Status, String, String, String)
method:Callback from the Enabler notifying an event related with notifier state change.
The Parent Sbb Abstract Class must implement the callbacks on it's SbbLocalObject, that is, must implement the org.mobicents.slee.sippresence.client.PresenceClientControlParent
interface discussed in last section.
The Enabler's Sbb is a Child Sbb, and JAIN SLEE 1.1 Child Relations requires an abstract method in the Sbb Abstract Class, to retrieve the javax.slee.ChildRelation
object, which is used to create or access specific Child Sbbs. This method should be:
public abstract ChildRelation getPresenceClientChildRelation();
The Parent's Sbb must define a reference to the Enabler's Child Sbb, declare which is the method name to get the related ChildRelation object, and also ensure the SbbLocalObject interface is defined correctly.
A reference to the Enabler's Child Sbb is defined right after the Parent's Sbb Vendor ID element, using the following XML element:
<sbb-ref>
<sbb-name>InternalPresenceClientControlSbb</sbb-name>
<sbb-vendor>org.mobicents</sbb-vendor>
<sbb-version>1.0</sbb-version>
<sbb-alias>presenceClientChildSbb</sbb-alias>
</sbb-ref>
The method name to get the Enabler's ChildRelation object must be defined after the CMP Fields (if any), this XML element links the sbb-alias previously defined with the abstract method declared in the Parent's Sbb Abstract Class:
<get-child-relation-method>
<sbb-alias-ref>presenceClientChildSbb</sbb-alias-ref>
<get-child-relation-method-name>getPresenceClientChildRelation</get-child-relation-method-name>
<default-priority>0</default-priority>
</get-child-relation-method>
Finally, after the sbb-abstract-class
element the Parent's SbbLocalObject interface name is defined:
<sbb-local-interface>
<sbb-local-interface-name>...</sbb-local-interface-name>
</sbb-local-interface>
In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.
The Mobicents Presence Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sippresence.client.PresenceClientControlSbbLocalObject
, which extends the javax.slee.SbbLocalObject
and org.mobicents.slee.sippresence.client.PresenceClientControl
interfaces, the latter declares the methods which can be used to interact with the PS and/or RLS:
package org.mobicents.slee.sippresence.client;
public interface PresenceClientControl {
public void setParentSbb(PresenceClientControlParentSbbLocalObject parentSbb);
public void newPublication(Object requestId, String entity,
String document, String contentType, String contentSubType,
int expires);
public void refreshPublication(Object requestId, String entity,
String eTag, int expires);
public void modifyPublication(Object requestId, String entity, String eTag,
String document, String contentType, String contentSubType,
int expires);
public void removePublication(Object requestId, String entity, String eTag);
public void newSubscription(String subscriber,
String subscriberdisplayName, String notifier, String eventPackage,
String subscriptionId, int expires);
public void refreshSubscription(String subscriber, String notifier,
String eventPackage, String subscriptionId, int expires);
public void removeSubscription(String subscriber, String notifier,
String eventPackage, String subscriptionId);
}
setParentSbb(PresenceClientControlParentSbbLocalObject)
method:Passes the Parent's SbbLocalObject, which will be used by the Child Sbb to provide async results. If not invoked after the child creation the Enabler won't be able to callback the Parent Sbb.
newPublication(Object, String, String, String, String, int)
method:Requests a new publication, for the specified Entity. The object argument is an ID that identifies the publication, and which will be provided in the response callback.
refreshPublication(Object, String, String, int)
method:Requests a publication refresh, for the specified Entity and ETag. The object argument is an ID that identifies the publication, and which will be provided in the response callback.
modifyPublication(Object, String, String, String, String, String, int)
method:Requests a publication modification, for the specified Entity and ETag. The object argument is an ID that identifies the publication, and which will be provided in the response callback.
removePublicationOk(Object, String, String)
method:Requests a publication removal, for the specified Entity and ETag. The object argument is an ID that identifies the publication, and which will be provided in the response callback.
newSubscription(String, String, String, String, String, int)
method:Requests a new subscription.
refreshSubscription(String, String, String, String, int)
method:Requests a subscription refresh.
removeSubscription(String, String, String, String)
method:Requests a subscription removal.
The Child Relation in the Parent Sbb Abstract Class is used to create and retrieve the Child Sbb, it is important to not forget to pass the Parent's SbbLocalObject to the Child after creation:
public PresenceClientControlSbbLocalObject getPresenceClientChildSbb() {
final ChildRelation childRelation = getPresenceClientChildRelation();
if (childRelation.isEmpty()) {
try {
// creates new instance
PresenceClientControlSbbLocalObject sbb = (PresenceClientControlSbbLocalObject) childRelation.create();
// passes the parent sbb local object to the child
sbb.setParentSbb((PresenceClientControlSbbLocalObject) sbbContext.getSbbLocalObject());
return sbb;
} catch (Exception e) {
tracer.severe("Failed to create child sbb", e);
return null;
}
}
else {
// reuse the existent one
return (PresenceClientControlSbbLocalObject) childRelation.iterator().next();
}
}
The SbbLocalObject of the Child could also be stored in a CMP Field for the simplest retrieval, but unless you are going to reuse each instance several times it's better to have less state, specially in clustered environments.